@Database PriMan.guide
@Remark $VER: PriMan.guide 2.0 (13.11.94)
@Node Main "Welcome to PriMan!"
                  PriMan v2.0 - The Task Priority Manager
                    Copyright 1993, 1994 Barry McConnell
  @{" Distribution     " Link Distribution}  Something about setting off World War 3...
  @{" Overview         " Link Overview}  Why PriMan exists, and what it does.
  @{" Installation     " Link Installation}  Where do all these icons go?
  @{" Usage            " Link Usage}  How to make it go PING!
  @{" Author           " Link Author}  Barry wants to hear from you!
  @{" Acknowledgements " Link Acknowledgements}  My director, my make-up artist, ...
  @{" History          " Link History}  Things which happened aeons ago.
  @{" Future           " Link Future}  PriMan will have them ... soon :-)
                    @{fg shine}PriMan - Don't leave home without it!@{fg text}
@Endnode
@Node Distribution "Spread me far and wide"
Distribution:
This program is Freeware.  You may freely distribute it, and charge only a
small fee to cover expenses.  It must remain unmodified, and accompanied by
this doc file.
I would like it if the source code followed PriMan around, but this is not
strictly necessary.  The source is there for you to learn from - feel free to
use small pieces of it in your own programs.  If you use it to create a new
version of PriMan and then redistribute it, or if you use large portions of
it in commercial software, I will naturally get @{" upset " Link Upset}.
Fred Fish is explicitly given permission to place this program on his fine
disk collection.  Urban Mueller may also do what he likes with it, Aminet-
wise.
If you like PriMan, or have any bug reports or suggestions, please send me a
message via e-mail (or a postcard, if you don't have access to Internet or
FidoNet).
As with any free software, you use PriMan entirely at your own risk.  If you
manage to start off World War 3 by discovering a bug, then I can not be held
responsible...
@Endnode
@Node Overview "Hey, this is quite useful actually..."
Overview:
PriMan is a fully Style Guide-compliant program for viewing a list of all
running tasks, and performing some actions on them.  The window in which the
list appears can be resized, the fonts used can be chosen from a settings
window, and customised settings can be stored in the ToolTypes.  PriMan
requires at least Kickstart 2, and takes advantage of a few extra features
available under Kickstart 3, although you probably won't notice these unless
you examine the source code carefully. :-)
PriMan allows you to change the priority of any task with the greatest of
ease.  Unlike most other similar utilities, you need only drag a slider to
change the priority - there is no messy clicking in string gadgets, deleting
the old priority, and typing in a new one.  There is also the facility to
signal tasks (e.g. with Ctrl-C), remove them from memory, and freeze them. 
And if you like to have it handy all the time, there is an Iconify option, as
well as the ability to leave it running in the background all the time as a
Commodity.
All of PriMan's functions are available using both the keyboard and the mouse.
To find out some of the theory behind PriMan's use, @{" Click Here " Link Priority}.
@Endnode
@Node Installation "What do I do first?"
Installation:
PriMan itself is not fussy about where it goes.  If you like to have it
running in the background all the time, I recommend placing it in WBStartup,
ensuring the DONOTWAIT ToolType is set (see @{" ToolTypes " Link ToolTypes}), and configuring
it not to open on startup (see @{" Commodity Settings " Link Commodity}).
If you want the @{" Online Help " Link Help} facility, put PriMan.guide in the same directory
as PriMan, or somewhere in your AmigaGuide path (see the file
"ENVARC:AmigaGuide/PATH").
If you have an older version of PriMan running as a Commodity, you will of
course need to remove that before starting this version - if you don't, all
that will happen is that the old version will pop to the front!
@Endnode
@Node Usage "Don't touch that button..."
Usage:
  @{" Starting Up     " Link Startup}
  @{" Main Window     " Link MainWindow}
  @{" Settings Window " Link Settings}
  @{" ToolTypes       " Link ToolTypes}
  @{" Online Help     " Link Help}
@Endnode
@Node Startup "Getting the ball rolling"
Starting Up:
PriMan works both from the Workbench and the Shell.  In both cases, it opens
the PriMan.info file and gets the initial settings from the @{" ToolTypes " Link ToolTypes}.  If
it can't find the .info file when running from the Shell, or some of the
ToolTypes are missing, then it uses the internal defaults.
When running from the Shell, you can specify any of the ToolTypes as command-
line options, and these will override the ones in the .info file.
Additionally, if the first command-line option is "?", PriMan will just give
a short piece of help text and immediately exit.
If you specify "HELP" as a ToolType or Shell command-line argument, the
@{" Online Help " Link Help} facility will be used - PriMan will launch normally, and
behave as if you pressed the Help key.
When running from the Shell, if the .info file can't be found, then you won't
be allowed to save your settings from the @{" Settings Window " Link Settings}.  Normally, the
imagery for the AppIcon (when iconified) is the same as the .info file, but
in this case it will use that of the system default tool (found in
ENV:sys/def_tool.info).
If you have configured PriMan to run as a @{" Commodity " Link Commodity}, and there is already
another PriMan running as a Commodity, then the one just started will
immediately exit, and the original one will bring itself to the front just as
if you pressed its hotkey.
If PriMan is running as a Commodity or has the @{" Iconify " Link General} option enabled, and
the CX_POPUP @{" ToolType " Link ToolTypes} is set to NO, then the main window won't open, and
PriMan will sit quietly in the background waiting for you to wake it up.
PriMan responds to Ctrl-C signals, and if you send it one of these (e.g. from
another running PriMan, or from the Shell it was started from), it will
immediately abort (unless a system requester was open).  A Ctrl-F signal will
tell it to open its main window (just like waking it up from Commodities
Exchange).
@Endnode
@Node MainWindow "Playing God"
Main Window:
@{b}Task List@{ub}  The big task list gadget is where all the tasks are displayed,
with their current priority in the second column.  You can use the mouse to
scroll around the list and select tasks, or the up and down cursor keys to
move through the list.  Shift-Up selects the first task in the list, and
Shift-Down selects the last task.
@{b}Update List@{ub}  This menu item updates the task list, which is useful if some
tasks have been created or removed since PriMan last updated it. Note that this
operation is very expensive, as it must disable task switching and
interrupts, before walking through both of Exec's task lists, making a copy
of each entry, and sorting them into alphabetical order.  Thus you may get a
serial error if you are doing a modem transfer, or the pointer may "flash" if
you are using @{" LacePointer " Link LacePointer} on a slow Amiga.  I have tried to optimise the code
as much as possible to ensure this won't normally happen.  You can also use
the Space and Return keys to update the list.
@{b}Priority@{ub}  To change the currently-selected task's priority, use the slider
gadget below the task list.  You can drag the slider and let go to make a big
change in the priority (the priority will be changed when you let go), or
click to the left or right of it to change the priority in steps of one.  You
can also use the right and left cursor keys to increment and decrement the
priority, respectively.  Pressing Shift at the same time moves to the
extremities of the slider.
The Priority menu item has a few presets, which could be quicker than
dragging the slider.  A useful shortcut is "Amiga =" which sets the priority
to zero.
@{b}Wide Slider@{ub}  Normally, the priority slider gadget displays task priorities
between -25 and +25, as it is unusual to find a task with an extremely low or
extremely high priority.  By checking this menu item, the full scale can be
used, allowing you to move the slider outside the -25 to +25 range.  This
operation is done automatically if you select a task that happens to have a
priority outside this range, and the menu item will also be disabled until
you move the slider back inside the range (since you can't have a narrow
scale when the current priority is large!).
@{b}Signal@{ub}  A task can be signalled with any of the following:
- Ctrl-C (please abort)
- Ctrl-D (task-specific; often means disable)
- Ctrl-E (task-specific; often means enable)
- Ctrl-F (show yourself; used mostly with Commodities)
Only Ctrl-C is widely-used by Amiga programs, and if you want to remove a
task, you should try this first.  It is a nice way of letting something know
you want it to finish, as it gives it a chance to clean up after itself.
PriMan will wait for half a second after sending the signal, to give the task
a chance to exit, before updating the task list.  If the task doesn't listen
for Ctrl-C signals, nothing will happen.
All four of these signals can be sent using the Signal menu item.  They have
the obvious keyboard shortcuts Ctrl-C, Ctrl-D, etc.  Additionally, the Break
button below the slider sends a Ctrl-C signal to the current task.
If you hold down Shift while using any of these (e.g. Shift-Ctrl-C, or Shift
while clicking on the Break button), the "Really signal ...?" confirmation
requester will not appear.
@{b}Kill@{ub}  The Kill button (or menu item) is nastier than sending a Ctrl-C signal,
as it doesn't give the task a say in the matter.  It just removes it from
memory, meaning any memory regions may not be freed up, resources will not be
available to other tasks, etc.  You should only really use this as a last
resort for tasks that have gone out of control.
Note that removing a task that has exited since PriMan's display was last
updated is NOT a good idea!  PriMan does some simple checking to ensure you
don't do this, but it is not 100% foolproof.  (98%, actually. :-) )  If your
Amiga crashes because you told PriMan to remove a non-existent task, you have
nobody to blame but yourself...
If the task has any windows or screens open, PriMan will ask you if you want
to close them as well.  Likewise, it is not a good idea to answer "yes" to
this question if, since putting up the requester, the windows or screens have
already been closed.  Your Amiga will certainly crash if you do this.
@{b}Frozen@{ub}  It is possible to "freeze" a task, and later let it resume execution.
If you check this menu item, the current task gets frozen.  You can even quit
PriMan and come back later to melt it (by unchecking it)!  Frozen tasks are
bracketed in the task list.  Since AmigaOS does not contain this feature, I
had to do a bit of "heavy magic" to get it to work.  So I don't guarantee the
reliability of this option under future OS releases (although it should
work).  Note that even if a task is frozen, messages sent to it (e.g.
keypresses in a text editor) will still be received once it wakes up!
@{b}Size Gadget@{ub} (lower right border of window)  You can make the window small
enough to accommodate only two tasks in the list, or large enough to fill the
screen.  All the gadgets in the window will be redrawn to fit in with the new
window size.  PriMan will automatically perform an Update List if you resize
the window, attempting to keep the current task selected, and leaving roughly
the same part of the task list visible.  (It is better at this under
Kickstart 3).
@{b}Settings@{ub}  This button (or menu item) will open up the @{" Settings Window " Link Settings}.
@{b}About@{ub}  This menu item brings up some additional information.  Clicking
the Help button in the requester will start PriMan's @{" Online Help " Link Help}.
@{b}Hide@{ub}  If you have PriMan running as a @{" Commodity " Link Commodity}, or with the @{" Iconify " Link General}
option enabled, this menu item will close down its windows but leave it
running in the background.  This is the same as clicking the close gadget on
the main window.  If PriMan is not running as a Commodity and can't be
iconified, Hide will be ghosted, and clicking the close gadget performs a
Quit (below).
@{b}Quit@{ub}  This menu item will also close down PriMan's windows, but in addition
unloads it from memory.  This is how you would kill PriMan for good if you
have the Commodity or Iconify options enabled.  The Escape key also performs
this task, and works from both the main window and the @{" Settings Window " Link Settings}. 
Please be gentle with this feature. :-)
@Endnode
@Node Settings "Customising your very own PriMan"
Settings Window:
The settings window is where you configure PriMan.  The main window can still
be used while this window is open.  It is divided into three pages, which can
be switched between using the Page cycle gadget at the top of the window.
  @{" Interface " Link Interface}
  @{" Commodity " Link Commodity}
  @{" General   " Link General}
Three buttons (at the bottom of the window) are common to each page:
@{b}Save@{ub}  This will write out your settings (including window size and position)
to PriMan's @{" ToolTypes " Link ToolTypes}.  Any ToolTypes already present that PriMan
does not recognise will be preserved.  If you have changed the window type or
chosen a new font, the main window will be redrawn.
@{b}Use@{ub}  PriMan will use these settings, but not write them out to disk.
@{b}Cancel@{ub}  Go back to the main window without making any changes.
@Endnode
@Node Interface "What shall I wear today?"
Interface Settings:
@{b}Gadget Font@{ub}  This will bring up the standard ASL Font requester, where you
can select the font used for all the buttons.
@{b}List Font@{ub}  A different (non-proportional) font needs to be used for the
task list, as otherwise the second column would not line up properly. This is
where you select it.
@{b}Window Type@{ub}  Amiga windows can be one of two different types.  Smart Refresh
windows maintain an off-screen bitmap of the entire window at all times, so
if part of it is obscured by another window, and later revealed, the OS just
copies the bitmap back into the window.  Simple Refresh windows don't have
this off-screen bitmap, and hence it is the application's responsibility to
refresh the window when necessary.  This is done by redrawing the individual
gadgets.  The disadvantage here is that if the application is tied up doing
something else (e.g. a system requester is open), its window won't get
refreshed until later.
On slow Amigas, Smart Refresh windows are faster.  If you have an accelerated
Amiga (or graphics card), you may find Simple Refresh windows more
responsive.  Try PriMan with both options (perform some window resizing,
dragging, and hiding behind other window) and see which suits you best.
@{b}Open On@{ub}  This simply tells PriMan on what screen it should open.  Default
Screen uses the default public screen (typically the Workbench screen), while
Front Screen uses the frontmost screen (assuming it's a public screen).
@Endnode
@Node Commodity "Catch me if you can!"
Commodity Settings:
By running it as a Commodity, you can leave PriMan quietly sitting in the
background, and open it at the touch of a key.  If PriMan's window is already
open and you use its hotkey, it will bring itself to the front.  PriMan will
also check what screen it is supposed to be on (using the @{" Open On " Link Interface} setting),
and jump to the correct screen if necessary.  This means you can, for
example, set Open On to Front Screen, and have PriMan follow you around as
you move between (public) screens, just by pressing its hotkey each time!
Note that if you have the settings window open while PriMan is jumping
between screens, it will re-open on the destination screen, but you will lose
any changes you have made since you last clicked Save or Use.  Sorry!
@{b}Install as a Commodity@{ub}  Should you not want PriMan to be a Commodity, you can
deselect this checkbox.  Note that when you click the Save or Use buttons
(see above), PriMan will install or remove itself as a Commodity, depending
on this setting.  If it tries to install itself, and finds another copy of
PriMan already installed, it will quietly exit, and the first copy will bring
itself to the front.
@{b}Popup When Launched@{ub}  If you are putting PriMan into your WBStartup drawer,
you may like to have this option deselected, so it will be silently started
each time you boot your Amiga.  Note that this option is ignored if you don't
have one (or both) of @{" Iconify When Closed " Link General} and Install as a Commodity
selected, as otherwise there would be no way of letting PriMan know when you
want it to open its window!
@{b}Hotkey@{ub}  If you have PriMan running as a Commodity, this is the keypress you
use to open its window.  Check out your Workbench manual to see the
acceptable combinations of keypresses.  If you give an invalid combination,
you will get a warning requester, although PriMan will continue on as normal.
@{b}Priority@{ub}  This is the Commodity priority PriMan runs at.  It is best left at
zero, and only really comes into play when two Commodities try to allocate
the same hotkey for themselves.  Note the difference between the Commodity
Priority and the @{" Task Priority " Link General}!
@Endnode
@Node General "The boring stuff"
General Settings:
@{b}Task Priority@{ub}  This is the Exec task priority PriMan runs at.  Most ordinary
applications run at a priority of 0 (and share CPU time amongst themselves).
System tasks run at higher priorities, to be guaranteed of getting CPU time
when they need it (which isn't too often).  If you are using PriMan to kill
off tasks which are chewing CPU time (e.g. they've gone into an infinite
loop), it is good idea to run it at a higher priority.  Once you have
verified that PriMan itself doesn't go into infinite loops ( :-) ), feel free
to set its priority to (say) 5, so it is always as responsive as possible,
regardless of what else is happening in your system.  The range is from -127
to +128.
If you change PriMan's priority from the @{" Main Window " Link MainWindow}, and then come here,
you will find the Task Priority box has been updated accordingly.
@{b}Confirm Actions@{ub}  If you are afraid of accidentally signalling or removing
a task, select this checkbox.  PriMan will then ask you for confirmation
before performing either of these actions.
@{b}Iconify When Closed@{ub}  If this is selected, whenever you click the close
gadget on the @{" Main Window " Link MainWindow}, an AppIcon will be placed on the Workbench
screen.  Double-clicking on this will open the main PriMan window again.
@Endnode
@Node ToolTypes "Carving your settings in stone"
ToolTypes:
PriMan takes its settings from the ToolTypes, held in the PriMan.info file
(accessed from Workbench by choosing the Get Info menu option).  Valid
ToolTypes include:
  @{fg shine}LEFT@{fg text}          left edge of window
  @{fg shine}TOP@{fg text}           top edge of window
  @{fg shine}WIDTH@{fg text}         window width
  @{fg shine}HEIGHT@{fg text}        window height
  @{fg shine}GADFONT@{fg text}       font used for gadgets (e.g. "Topaz.font")
  @{fg shine}GADSIZE@{fg text}       height of GADFONT
  @{fg shine}LISTFONT@{fg text}      non-proportional font used in the task list
  @{fg shine}LISTSIZE@{fg text}      height of LISTFONT
  @{fg shine}ICONLEFT@{fg text}      left position of AppIcon
  @{fg shine}ICONTOP@{fg text}       top position of AppIcon
  @{fg shine}REFRESH@{fg text}       SMART|SIMPLE - the @{" Window Type " Link Interface} setting
  @{fg shine}SCREEN@{fg text}        DEFAULT|FRONT - the @{" Open On " Link Interface} setting
  @{fg shine}CONFIRM@{fg text}       YES|NO - the @{" Confirm Actions " Link General} setting
  @{fg shine}ICONIFY@{fg text}       YES|NO - the @{" Iconfiy When Closed " Link General} setting
  @{fg shine}COMMODITY@{fg text}     YES|NO - the @{" Install as a Commodity " Link Commodity} setting
  @{fg shine}HELP@{fg text}          if present, @{" Online Help " Link Help} is given at startup time
The standard @{" Commodity " Link Commodity} ToolTypes also apply:
  @{fg shine}CX_POPUP@{fg text}      YES|NO - the Popup When Launched setting
  @{fg shine}CX_POPKEY@{fg text}     hotkey to open PriMan's window (or bring it to the front)
  @{fg shine}CX_PRIORITY@{fg text}   Commodity priority
Not forgetting some of the ones Workbench uses:
  @{fg shine}TOOLPRI@{fg text}       PriMan's @{" Task Priority " Link General}
  @{fg shine}DONOTWAIT@{fg text}     you need this if PriMan goes in WBStartup
PriMan's internal defaults will be used for any ToolTypes that are missing.
If you don't specify both a name and a height for either of the fonts, then
PriMan will use your Workbench Preferences settings for that font.  If it
can't find the font you ask for, you will get a warning requester, and
Topaz-8 will be used.
If you are a Shell user, you can put your favourite settings in the
ToolTypes, run PriMan just by typing "PriMan" (assuming it's somewhere in
your path), and - if necessary - override individual ToolTypes by passing
them as Shell arguments in the same format as above.
Note that you should never need to manipulate the ToolTypes directly yourself!
Let the @{" Settings Window " Link Settings} take care of this.  The only ToolTypes not currently
controllable from the settings window are the ones relating to the position
of the AppIcon - edit the PriMan.info file yourself if you need to put the
AppIcon in a specific place on the Workbench screen.
@Endnode
@Node Help "What on earth does this do?"
Online Help:
PriMan has an interface to AmigaGuide, and - assuming PriMan.guide is
available (see @{" Installation " Link Installation}) - will open it whenever you ask for help.  This
is done by pressing the Help key from either the @{" Main Window " Link MainWindow} or the
@{" Settings Window " Link Settings}, clicking Help in the About requester, or passing "HELP" as
a ToolType or Shell command-line argument.
The AmigaGuide window runs as a separate process, which means you can
continue to use PriMan while it's open.  Pressing the Help key again will
always bring you back to the first page in the help text.  Additionally, if
PriMan has moved to a different screen in the meantime, the AmigaGuide window
will follow it when you press Help.
The AmigaGuide handler I've written is quite simplistic, and it ignores any
errors.  So if PriMan.guide can't be found, nothing will happen.
Online help requires amigaguide.library, which you may not have installed if
you are still using Kickstart 2.04.
@Endnode
@Node Author "My people will be in touch with your people"
Contacting Me:
I can be reached via any of the following methods:
@{" Snail Mail " Link Snail}	Barry McConnell,
		"Piper's Hollow",
		Hillcrest Road,
		Dublin 18,
		Ireland.
@{" Internet " Link Internet}	bmccnnll@tcd.ie  (note new short address!)
@{" FidoNet " Link Fidonet}	2:263/150.2
My Internet address probably won't be valid after October 1995.
@Endnode
@Node Acknowledgements "Eternal gratitude"
Thanks:
I am deeply indebted to Eddy Carroll for giving me a lot of programming tips
while I was writing PriMan.  It was great having such a helpful Amiga guru
just an e-mail away; any interface similarities to @{" SnoopDos " Link SnoopDos} may be not
entirely coincidental. :-)
A big `thankyou' to James Young for doing the AmigaGuide conversion of the
doc file.  I never considered it necessary for PriMan to have documentation
in this format, but when I saw the final result, I liked it so much, I
scrapped the original ASCII doc file. ;-)
Thanks to my beta-testers: Eddy Carroll, Colin Dalton, Andrew Mowatt, Niall
Murphy and Kevin Phair.
Thanks to Tom Ekstr
m for the icon, and to Wouwe van AP for the one I didn't
Also thanks to everyone else who gave me feedback and ideas - you're all
mentioned in the History section.
SAS/C was used to create PriMan, purchased at the student price from the fast
and efficient SAS Germany.
@Endnode
@Node History "It happened like this..."
History:
  @{" Version 1.0 " Link v1.0}  3rd September 1993
  @{" Version 1.1 " Link v1.1}  29th September 1993
  @{" Version 2.0 " Link v2.0}  13th November 1994
@Endnode
@Node v1.0 "A child is born!"
Version 1.0:
- Initial release.
@Endnode
@Node v1.1 "What v1.0 should have been"
Version 1.1:
- Now complains if you try to "Break" or "Kill" it.
- Walks through Intuition's list of screens and windows when removing a task.
  If it finds any open windows belonging to that task, it asks you if you
  want to close them as well.  Currently doesn't close screens, because that
  is even more dangerous. :-)
- Moved around the code for building the task list, taking almost everything
  out of the Disable() ... Enable() section.  Now it just generates an array
  of pointers to the tasks when interrupts are disabled, and does the actual
  sorting later on.  This means your pointer is less likely to flash if you
  are using LacePointer, and serial I/O will be not be affected as badly. 
  Thanks to David Swasbrook for giving me the incentive to do this.
- Added in error messages if PriMan has to suddenly abort for any reason.  If
  you are _really_ low on memory, you may not get them...
- The settings window is now the same width as the main window, so PriMan no
  longer has to look at the width of the Gadget font when trying to fit a
  decent number of characters into the font boxes.  Thanks to James Young for
  spotting that PriMan did not work well with the Junod 8 point font (from
  the AmigaGuide archive).  The font structure appears to be flawed, and
  reports that it can be a maximum of 258 pixels wide...
- Fixed bug where you could still resize the main window when the "About"
  requester was open.
- Major changes to code means PriMan is now more multithreaded.  You can have
  the settings window (but not any system requesters) open, and still play
  around with the main window.
- Added an AppIcon feature, which can be turned on from the settings window. 
  If enabled, closing the main window will place an AppIcon on the Workbench
  screen, and double-clicking that will open the main window again.  To leave
  PriMan for good, press Escape.
- PriMan now accepts arguments from the Shell.
- Added a Commodity interface.  PriMan does everything you would expect when
  you play around with the Commodities Exchange program.  If you try
  launching PriMan twice, the original one will be de-iconified (if
  necessary) and then brought to the front.  The enable/disable buttons in
  Exchange do nothing to PriMan.  Pressing Escape in PriMan also removes it
  for good (like when using the Iconify option).
@Endnode
@Node v2.0 "Now the users are getting picky..."
Version 2.0:
It took me a while to get this one out the door (over a year!), due to the
demands of college and other committments.  I hope I remembered to include
all the changes I made!
- Source code has been cleaned up a LOT.  I liberally sprinkled comments all
  around it, and in doing so did heaps of rewriting.  (It's amazing how
  commenting your code forces you to think clearly about exactly what you're
  doing, and then you often find a better way...)  Note that the source is
  now in several files, and has its own makefile.
- Added menus, specially for Per Jacobsen. :-)
- Added keyboard shortcuts for all the gadgets.  Thanks to Eddy Carroll for
  showing me how to simulate buttons being pressed when their shortcut is
  used.  The cursor keys are also used: up and down move you through the
  task list, while left and right change the currently-selected task's
  priority.  Holding down Shift moves you to the extremity of the task list
  or slider gadget.
- Fixed an error in the error-handling routine. :-)  Sometimes if a really
  nasty error occurred (like running out of memory while trying to open the
  settings window), PriMan would forget to clean up after itself, and do
  wierd things if you tried playing with its window after the main task had
  exited.  Thanks to James Young for bringing this one to my attention (the
  only real bug in v1.1).
- Removed the close gadget on the settings window, since its meaning is not
  clear.  (Should it perform a Use or Cancel operation?  Standard Commodore
  requesters perform a Cancel where appropriate, but this is not immediately
  obvious for the new user.)  Note that it does still check for any
  IDCMP_CLOSEWINDOW events (Eddy Carroll's idea), so you can cancel it using
  something like WindowDaemon's Ctrl-\ shortcut.  (Although it's probably
  easier to just press 'C'!)
- Now watches for Ctrl-C signals (say from another PriMan...), and
  immediately aborts when one is received.  Thanks to Karl Jeacle for
  expressing horror when he noticed v1.1 didn't do this. :^)
- New default hotkey "control alt p" to conform to other Commodore
  Commodities.  Thanks to Matt Brookes for suggesting this.
- Now uses the title bar to indicate the number of tasks listed. Thanks to
  David Swasbrook for this idea.
- Moved around the code for generating the task list _again_, just to please
  David Swasbrook. ;-)  He was unhappy with the (negligible, IMHO) chance of
  a task exiting after interrupts had been re-enabled, but before its name
  had been placed into the sorted list (meaning when PriMan went to reference
  its structure from the pointer table it had built earlier, wierd things
  could happen).  So now PriMan builds a list of task pointers while
  interrupts are disabled, copies their names and priorites while interrupts
  are enabled but multitasking disabled, and finally sorts the list after
  re-enabling multitasking.  (See the source code for more detail on this.)
  This means the system is locked up for slightly longer than in v1.1 (but
  nowhere near as long as in v1.0); however there is no discernible difference
  on my A3000, and I hope this is okay for 68000 users.
- Added shortcuts to bypass the confirmation requesters when signalling or
  removing tasks, for Kevin Phair.  If you hold down Shift when selecting the
  Break or Kill buttons (or menus), you don't get the requester.  Thanks to
  Eddy Carroll for a little bit of help here.
- Now has the option to close screens as well as windows, for Niall Murphy.
  (I was going to do it anyway, okay Niall?)
- Settings window has a new "Task priority" gadget, where you can enter the
  priority you want PriMan to run at.  This functionality was always
  available via the standard Workbench TOOLPRI ToolType, but since many
  people (Kevin Phair @{i}et al@{ui}) didn't know about this, I have now made it
  explicit.
- Added menu items to change the task priority to preset values, for Panu
  Hassi.  A bit simplistic at the moment, since the presets are hard-coded.
- Now has the option to freeze tasks.  This idea came from Burnand Patrick -
  thanks for your postcard, Burnand!  In a @{" Usenet " Link Usenet} article, Ingo Wilken
  described how to do this, and I am very grateful to him.
- The settings and font windows are now indented a little from their parents,
  since Niall Murphy gets less confused this way. :)
- Minor bugfix (okay, the *second* bug in v1.1).  PriMan had the potential to
  get very confused if it was started from Workbench, but didn't find a .info
  file.  Thanks to Eddy "hawk-eyes" Carroll for spotting the spurious
  semicolon at the end of an 'if' statement in my source. :-)
- PriMan is now Virtual Memory friendly.  Where memory is used while
  interrupts are disabled, it is allocated as PUBLIC memory.  This will make
  programs such as VMM much happier.  Thanks for the beta copy of VMM030,
  Martin Aspel!
- PriMan is 'sysihack'-aware.  It adjusts if the bottom border of its window
  becomes larger than the 2.x/3.x defaults.  Thanks to Eddy for showing me
  the easiest way of doing this.  (See the source code!)
- All-new settings window.  I figured there were too many options to display
  in one window without potentially confusing the casual user, so it now
  displays one page at a time, out of three.
- Rather than always opening on the default public screen, PriMan now has the
  option to open on the front screen instead.  If the front screen is not a
  public screen, it opens on the default public screen anyway.  I also added
  a little bit of code to check the default or front screen when PriMan's
  hotkey is pressed but its window is already open, and reopen its window if
  the screen it's currently on is not the "correct" one.  Actually, this is a
  blatant rip-off of the way SnoopDos 3.0 works - thanks, Eddy!
- Now lets you choose if you want a SIMPLE_REFRESH or SMART_REFRESH window.
- Signal menu item lets you choose which signal to send to a task, or you can
  just press Ctrl and the signal type.  PriMan itself responds to the standard
  Commodity Ctrl-F signal (meaning "show yourself").  It was Wouwe van AP's
  idea to allow sending signals other than Ctrl-C.
- The font requesters are smarter: the first one to open takes up 2/3 of the
  current screen's height, and the second one will take its initial
  dimensions from the first one.  Thanks to Eddy for his suggestion.
- Additionally, if PriMan can't find any settings at all, it uses similar
  screen-related code to determine sensible initial window dimensions and
  positions.  (See the source code!)
- Changed the Commodity code a bit so the CX_PRIORITY will get updated
  immediately if you change it from settings, rather than the next time you
  launch PriMan.  The side-effect is that - where applicable - PriMan now
  quickly removes itself as a Commodity then adds itself back in whenever you
  click Use in the settings window.
- If you click on a task, then update the list (either by selecting the Update
  List menu or its keyboard equivalents; or by resizing the window), the task
  will remain selected afterwards (assuming it still exists).
- PriMan now has online help.  If you press the Help key, AmigaGuide goes off
  and looks for the PriMan.guide file.  It even follows PriMan around screens:
  if you jump to a different screen and press Help, the AmigaGuide file will
  follow you.  A quick peek at SnoopDos's source clarified how to get
  asynchronous AmigaGuide support working.  HELP is now a ToolType (and works
  from the Shell) if you want online help at startup time.
- More support for Shell users (at Eddy's request).  PriMan first looks for
  its .info file, and reads in the ToolTypes from that.  Then if you specify
  any additional arguments on the command line, they will override the
  ToolTypes.  If the first argument is "?", you'll get a short help message
  and PriMan will exit.  Finally, clicking Save in the settings window will
  write the current settings out to the .info file.  Naturally, if it can't
  find this then the Save button will be ghosted as before, but you can still
  use the Iconify option, and this will use the imagery of the system default
  Tool icon (ENV:sys/def_tool.info).
- Phew!  After all this, the executable has barely increased in size since
  the last version, due to some clever optimisation...
@Endnode
@Node Future "Things worth considering"
Future Additions:
- String gadget to enter a new priority.  (Matt Brookes)
- MultiUserFS support: indicate task's owner somewhere.  (David Swasbrook)
- Icon position window a la ToolManager, so you can precisely position the
  AppIcon instead of by trial-and-error.  (The ToolTypes to control its
  location are the only ones you need to manually change from the Workbench
  Info menu.)  (Andrew Mowatt)
- Indicate CPU usage, or at least whether a task is awake or asleep.  (Kevin
  Phair)
- Allow iconifying to the Workbench Tools menu, if anyone asks for this.
- Improve the AmigaGuide handler, so it reports errors, etc.
Things I don't plan to do include:
- Full context-sensitive online help.  (It isn't really necessary!)
- Anything not directly related to tasks (e.g. lists of devices or
  libraries), the reason being PriMan is supposed to be a small Commodity
  with a fairly focused purpose in life.
- Programmer info (e.g. a dump of the task's structure).  There are plenty of
  other utilities out there if you really need this - PriMan is intended to be
  the kind of thing that would have been included in the OS if the designers
  had had more time...
@Endnode
@Node Priority "So you're still not convinced?"
Why Do I Need PriMan?
The Amiga is a multitasking computer.  This means that while it only has one
CPU (one of the M680x0 series), it can - seemingly - run many programs at the
same time.
To get a simple idea of how this works, imagine a certain part of the OS is
in control of the CPU.  It has a list of all the running programs (tasks),
and allots a fixed amount of time to each one.  When one task runs out of
time, it is suspended and the next one gets to run.  With small-enough time
slices, this gives the illusion that all are running at the same time.
Tasks actually spend most of their time doing nothing (waiting for the user
to press a key, waiting for a disk operation to complete, etc.).  So the OS
maintains two lists: one for tasks that are doing something (e.g. your
ray-tracer doing a rendering operation), and the other for tasks that are
waiting for something to happen or an operation to complete (e.g. your
word-processor when you aren't using it).
The more tasks on the "ready" list (doing something), the more loaded your
Amiga is, and less responsive it appears to get.  By judicious use of task
priorities, you can maximise its performance.
Each task has a priority, between -128 and +127, with 0 being the usual.  Put
simply: the OS divides up the available CPU time between the tasks with the
highest priority, and ignores the rest.  If all tasks are running at priority
0, then they all get equal time.  Some important system tasks (e.g. Workbench
or your hard disk controller) are put at higher priorities.  These spend most
of their time asleep, but when they need to run, they get the CPU pretty much
immediately (whatever task was currently running at a lower priority gets
suspended to make way for the higher-priority task).
As it turns out, the most important (system) tasks don't need to run very
often, and it's quite safe to leave them at high priorities (this is done
automatically).  Whenever you launch an application, it gets put at priority
0 by default.
Where PriMan comes in handy is when you have - say - a ray-tracer running for
several hours.  If you try to do something else (say word-processing) with
the ray-tracer in the background, it will be slowed down since it's sharing
CPU time with the ray-tracer.  By using PriMan to lower the ray-tracer's
priority to (say) -1 or -5, your word-processor will get all the CPU time it
needs, and when it's not processing your keypresses or doing some printing,
the ray-tracer will get back its CPU time.
Of course, PriMan has a host of other features, such as being able to signal
tasks, kill them, freeze them ... so why not drop it in your WBStartup drawer
right now? :-)
@Endnode
@Node Upset "Not for the faint-hearted"
Getting upset:
Some folk, when they get upset in this manner, go to great lengths in order
to (legally) extract large amounts of money from you.  Others will force you
to suffer public humiliation.  Still others will shoot your dog.  Pick your
personal worst-case scenario, then don't break my rules for distributing
PriMan. :^)
@Endnode
@Node Snail "Has it arrived yet?"
Snail Mail:
Snail Mail is the term used by e-mail junkies - who are used to messages being
beamed around the world in a matter of minutes (or seconds) - to describe
"normal" mail.  That is, mail which you put in an envelope, put a stamp on,
and deposit in a mail box, then wait "only" a week for it to get from Ireland
to the UK. :-)
@Endnode
@Node Internet "More addictive than heroin"
The Internet:
The Internet is by far the world's largest electronic network.  It
incorporates an e-mail system from which you can contact people all over the
world almost instantly.  It has an estimated population in the tens of
millions, and grew out of the ARPAnet, a network founded in the late 1960's
by the US Defense Advanced Research Projects Agency.  More information can be
found in the @{" EFF " Link EFF}'s "Big Dummy's Guide to the Internet".
[Sheesh, James: you _have_ been doing your homework! :-) ]
@Endnode
@Node Usenet "I was so busy today, I only had three hours to read Usenet..."
Usenet:
Usenet is a global conferencing system, accessed via the @{" Internet " Link Internet}.  It
contains thousands of "newsgroups", where people can leave public messages
for others to read.  Topics include computers (obviously!), music, TV,
cooking, animals, and much, much more.  It is a goldmine of information, as
you can post a message on any newsgroup and expect replies back within 24
hours.
@Endnode
@Node EFF "The net.police are after you!"
The EFF:
The EFF (Electronic Frontier Foundation) is an organisation set up in 1990 to
deal with the growing problems of e-mail networks, to represent them, offer
legal advice to those accused of computer crime, and to publicise e-mail as
the way ahead for communications.
@Endnode
@Node Fidonet "Who let that dog in here?"
FidoNet:
FidoNet is the world's largest amateur e-mail network, with around 24,000
nodes (main carriers of the e-mail; these are mostly @{" BBSes " Link BBS}), and countless
numbers of users, many of which are @{" Points " Link Point}.
@Endnode
@Node BBS "There's a whole new world out there!"
BBSes:
A BBS (Bulletin Board System) is a system where people with modems (a
device to translate digital computer data into an analogue signal which the
telephone network can understand) can dial in to send and receive files and
messages, as well as playing online games and talking to other users who are
logged in at the same time.
@Endnode
@Node Point "When the phone bill gets too big"
Points:
A point is basically an automated offline mail-reader.  A piece of software
calls the @{" BBS " Link BBS} for you to download any waiting mail in a compressed packet.
At the same time, it uploads your replies to the last packet of mail you
received, and can even request files from the BBS's file areas.  If you leave
your computer on all night, you can set up a system whereby the call is made
for you in the middle of the night (when the phone charges are the
cheapest!), and when you wake up in the morning, your mailreader is sitting
there ready for you to read the mail!
@Endnode
@Node LacePointer "For every flicker-fixer user"
LacePointer:
When running in interlace mode on non-AGA Amigas, the pointer is still a low-
resolution sprite.  For people with flicker-fixers installed (e.g. the
A3000's Display Enhancer), this detracts from the professionality of the
system.  LacePointer is a system hack which effectively makes the pointer
appear to be in a higher resolution (by putting it in interlace mode too).
@Endnode
@Node SnoopDos "Eddy Carroll's masterpiece"
SnoopDos:
SnoopDos is a utility that allows you to monitor a variety of system
operations carried out by programs on your Amiga.  This includes what files a
program is trying to open, what fonts, libraries, devices and environment
variables it is looking for, and so on.
It is invaluable when trying to find out why a particular program won't work,
or when you are suspicious about what something is doing to your hard drive.
SnoopDos should be available through the same channels as PriMan, or you can
e-mail its author at <ecarroll@maths.tcd.ie>.  The source code is included
(in a separate archive), and is a goldmine of useful information for budding
Amiga programmers.
@Endnode